ctkmu

Key Management Utility for the ProtectToolkit-C environment, used for ProtectToolkit-C token management. This includes operations required by a token’s SO, such as setting user PINs and re-initializing tokens, as well as those operations required by the normal User, such as object management.

A number of commands can be used with the ctkmu utility to help with key creation, deletion, import, export, as well as PIN change, token initialization and replication.

Syntax

The following ctkmu syntax can be used.

Commands

The following ctkmu commands are available.

c

This command is used to generate new keys on the specified token. The -a parameter is used to specify the attributes, the -n parameter specifies the key’s label and the -t parameter the new key type. PKCS#11 attributes contains further information on key attributes. Common uses for this command are generation of a random key, import of a split custodian key (using the -k flag), or creation of a split custodian key (using the -g and -k flags). When importing a split custodian key, optionally, a supported PIN pad device can be used (using the -p flag) to ensure that the key components are entered directly to the device.

d

This command is used to delete a key on the specified token. This command will permanently destroy the key with the label specified with the -n parameter.

e

This command is used to erase a smart card in the specified slot and will leave the smart card in an uninitialized state.

i

This command is used to import keys previously exported with the export command (see below).

idp

This command is used to store Domain Parameters objects onto a Token.

The -s option indicates the slot. For example, -s1 for slot 1. (Default is slot 0).

The -n option indicates the label of the new object.

The -t option specifies the key type, it may be ec or dsa or dh but only ec is supported.

The -a option allows attributes to be specified. Only the ‘P’ private and ‘M’ Modifiable attributes are allowed. The default attribute if -a option is missing is CKA_PRIVATE=false and CKA_MODIFIABLE=false.

The <filename> option specifies a test file that contains the information required to construct the domain parameters.

itr31

This command is used to import a new key object into a token.

If the key block contains a private key pair, then the header may also include a public key certificate. If a recognized X509 certificate is contained in the header, then the tool will extract this certificate and prompt the operator to create a CKO_CERTIFICATE object from its value.

The object will be created with CKA_PRIVATE=True and CKA_MODIFIABLE=False. Other attributes will default to True, depending on the header content. You can then further restrict the attributes of the new object by using the ‘A’ option.

If the TR31 header specifies the key usage is ‘K1’ (TR-31 key block protection key), then the tool will add the attribute CKA_MECHANISM_LIST containing CKM_WRAP_TR31_DERIVE + CKM_WRAP_TR31_DERIVE_CTR + CKM_WRAP_TR31_VARIANT and/or CKM_UNWRAP_TR31, depending on the key type, mode, and usage.

The -s option indicates the slot. For example, -s1 for slot 1. (Default is slot 0).

The -n option indicates the label of the new object.

The -w is the label of the unwrap key (DES2, DES3, or AES key types only).

The -A option allows attributes that normally default to True to be set to False. Only certain attributes are allowed. For a list of attributes that can be set to False, see -A<attributes> below.

The ––keyCertLabel can be used to override the label of any public key certificate extracted from the key block and imported to the HSM.

filename is the path to a file containing a TR31 key block.

Note

This command is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

j

This command is used to import a Private Key and a Certificate from a PKCS#12 file format.

l

This command is used to display information on the objects stored on the token in the specified slot. This command will list the actual keys, certificates and other objects, or, if the token is a smart card token previously used with the key export function information on that key backup set.

m

The Modify Attributes command is used to change the specified attributes from True to False and vice versa, or add the attribute if it does not exist.

Note

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer and the object does not contain a CKA_TR31_INFO attribute, this command can be used to add one using the -e or -E options.

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer and the object does not contain a CKA_MECHANISM_LIST attribute, this command can be used to add one using the --mech-list option.

p

The Pin command ‘p’ is used to initialize the User PIN or to change an existing PIN (either the User or SO PIN) the command will prompt.  'Cannot change the pin for the token in slot 1 as it is not initialized. You can use the command ctkmu t -s 1 to initialize this token.'

If the PIN is initialized the current PIN will be prompted for before the new PIN can be specified.  To change the SO PIN, specify the -O option.

rt

The replicate token command 'rt' is used to replicate a source token to one or more destination tokens. The -s parameter identifies the source token to be replicated, by default slot 0 is used. The -d parameter specifies one or more destination tokens to replicate the source token to.

If an error occurs replicating to a particular token, an error will be reported and that token will be skipped. This prevents offline or faulty devices from spoiling the replication process for other tokens.

To complete this operation, ctkmu will prompt for the user PIN of the source token.

When replicating to an uninitialized token, ctkmu will prompt for the SO PIN of the destination token. If the device is running in FIPS Mode, ctkmu will prompt for the device administrator PIN of the destination token.

s

The Smart Card status command ‘s’ is used to display information on the smart card token currently inserted in the specified slot. Details of the keys exported to the token will be displayed.

t

The Initialize/Reset Token command ‘t’ allows for existing tokens to be initialized or re-initialized.  If the specified token contains an initialized token the current SO PIN will be prompted for before a new Token label can be specified and the token re-initialized. If the token is uninitialized this command will only operate if the ‘No clear PINs’ flag is not specified for the HSM (otherwise only the Administrator can initialize tokens with the ctconf utility). In this case the new SO PIN and label can be specified. Once the token has been reset or initialized a new user PIN can also be set.

x

The Export Key command ‘x’ allows for keys to be exported to one or more smart cards or to a file or to the screen.

Keys exported to the screen are wrapped with standard algorithm and are suitable for transport to foreign systems. Keys wrapped for smart card or file backup use proprietary algorithms and can only be restored to compliant ProtectToolkit-based HSMs.

The main difference between the standard and proprietary methods is that the proprietary method wraps all the attributes of the key so that when a key is restored it must contain the same attributes as the original.

Keys wrapped for smart card backup can use one of two basic methods; keys can be exported as split custodian in which case they will be encrypted using a randomly generated key which is then split and distributed to a number of smart card tokens. Alternatively, a key wrapping key can be specified which will then be used to encrypt the key specified for backup. This encrypted data can then be written to a smart card token or to a file.

Please note that if the -j parameter is used to export a private key and certificate to a PKCS#12 file format the following considerations need to be made.  Exportable private key types are: RSA, DSA, and ECDSA.

• If the private key being exported is marked CKA_EXPORTABLE=TRUE and CKA_EXTRACTABLE=FALSE, the toolkit will prompt for Security Officer (SO) to login to perform the export operation.

• User performing the PKCS#12 private key export will be asked to provide two (2) passwords (one for Payload and one for HMAC). At this stage, the user must take into account which 3rd party tools will be used to extract the PKCS#12 file. For example, Microsoft Windows requires that the Payload and HMAC passwords be identical. OpenSSL, however, will extract Key and Certificate exported by ctkmu using two different passwords. The user needs to decide which password policy best suits their needs.

• The RC family of encryption algorithms (and others) are prohibited in FIPS Mode. ctkmu shall reject the command and display a warning message if they are used under this security policy.

Note

When logging in to a smart card, the card is locked after 7 consecutive incorrect PIN attempts. You must re-initialize the card to set a new PIN.

xtr31

This command is used to export a key object as a TR31 key block.

The -s option indicates the slot. For example, -s1 for slot 1 (Default is slot 0).

The -n option indicates the label of the exported object.

The -w is the label of the wrap key (DES2, DES3, or AES key types only).

The --tr31method option specifies the key binding method used. (Default is derive-cbc)

If the key to be exported does not contain a CKA_TR31_INFO attribute, then the TR31 Type 0 header should be specified using the -e or -E option. For more information about this attribute, see CKA_TR31_INFO.

The -e option specifies a header directly on the command line and is suitable for smaller headers with no optional extensions.

The -E option tells the utility to read the TR31 Type 0 header from a file.

The ––keyCertLabel can be used to specify a public key certificate to be added to the key block (as a CT extension).

filename is the path to a new file created by this command containing the TR31 key block. If filename is not specified, then the key block is displayed on the console.

Note

This command is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

Options

The following ctkmu options are available.

-a<attributes>, --attributes=<attributes>

Specifies attributes for an object/key.

When importing or creating an object (using a command other than itr31) the new object’s attributes default to 0.

This option can be used to enable the following attributes:

Value	Attribute
P	CKA_PRIVATE=1
M	CKA_MODIFIABLE=1
T	CKA_SENSITIVE=1
W	CKA_WRAP=1
w	CKA_EXPORT=1
I	CKA_IMPORT=1
U	CKA_UNWRAP=1
X	CKA_EXTRACTABLE=1
x	CKA_EXPORTABLE=1
R	CKA_DERIVE=1
E	CKA_ENCRYPT=1
D	CKA_DECRYPT=1
S	CKA_SIGN=1
V	CKA_VERIFY=1
L	CKA_SIGN_LOCAL_CERT=1
C	CKA_USAGE_COUNT=1 (can only be used with c command)

Note

You can only set CKA_EXPORTABLE to TRUE if you are using ProtectServer 3 HSM Firmware 7.02.00 or newer and have set the Weak PKCS#11 Mechanisms security flag. For more information about CKA_EXPORTABLE and setting the Weak PKCS#11 Mechanisms security flag, see CKA_EXPORT, CKA_EXPORTABLE and Weak PKCS#11 Mechanisms, respectively.

-A<attributes>, --disable-attributes =<attributes>

Specifies attributes for an object/key that should be set to False where the import operation would normally set them True.

When importing an object with the itr31 command the new object’s usage attributes default to values extracted from the key block.

This option can be used to force the following attributes:

Value	Attribute
P	CKA_PRIVATE=0
T	CKA_SENSITIVE=0
W	CKA_WRAP=0
w	CKA_EXPORT=0
I	CKA_IMPORT=0
U	CKA_UNWRAP=0
X	CKA_EXTRACTABLE=0
x	CKA_EXPORTABLE=0
R	CKA_DERIVE=0
E	CKA_ENCRYPT=0
D	CKA_DECRYPT=0
S	CKA_SIGN=0
V	CKA_VERIFY=0

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-c<slot>, --sc-slot-num =<slot>

Specifies the Smart Card slot to export to or import from.

-C<curve_name>, --curve-name =<label>

Specifies which curve to use. Valid values are:

• brainpoolP160r1

• brainpoolP160t1

• brainpoolP192r1

• brainpoolP192t1

• brainpoolP224r1

• brainpoolP224t1

• brainpoolP256r1

• brainpoolP256t1

• brainpoolP320r1

• brainpoolP320t1

• brainpoolP384r1

• brainpoolP384t1

• brainpoolP512r1

• brainpoolP512t1

• c2tnb191v1

• c2tnb191v1e

• curve25519

  Note

  Can only be specified if -t is set to ec_mont.

• curve448

  Note

  Only supported if you are using ProtectToolkit 7.2.0 or newer with ProtectServer 3 HSM Firmware 7.02.00 or newer.

  Can only be specified if -t is set to ec_mont.

• ed25519

  Note

  Can only be specified if -t is set to ec_edwards.

• ed448

  Note

  Only supported if you are using ProtectToolkit 7.2.0 or newer with ProtectServer 3 HSM Firmware 7.02.00 or newer.

  Can only be specified if -t is set to ec_edwards.

• P-192 (also known as prime192v1 and secp192r1)

• P-224 (also known as secp224r1)

• P-224K1 (also known as secp224k1)

• P-256 (also known as prime256v1 and secp256r1)

• P-384 (also known as secp384r1)

• P-521 (also known as secp521r1)

• secp256k1

• or any valid ECC Domain Parameter object label

-d<slotlist>, --dest =<slotlist>

Specifies a comma-separated list of tokens identified by slot number. The special value all denotes all initialized tokens with a token label identical to the source token label and where trust has been established between the devices.

<filename>

Specifies a file to be created for export or used to import a key, certificate, token, or set of domain parameters.

-e, --tr31-header=<TR31-header-String>

Specify the TR31 header contents when wrapping a key that does not have its own information in a CKA_TR31_INFO attribute.

Value must be a valid CKA_TR31_INFO attribute content. For more information about this attribute, see CKA_TR31_INFO.

Example:

--tr31-header=00016D0AB00N0000

Where-
00016 // ID 0 and Len 0016
D0    // Usage Sym Data Enc/Dec
A     // Algorithm AES
B     // Mode – Both Enc/Dec
00    // Vers
N     // Not Exportable
00    // No Optional Blocks
00    // Reserved

Optionally the string may start without a ‘0’ to indicate short format.

The short format does not include the first five characters (type and length) and any trailing characters will default to ‘0’.

Example:

--tr31-header=D0AB00N

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-E, --tr31-header-file=<TR31-header-file>

Specify the file to read the TR31 header contents from when wrapping a key that does not have its own information in a CKA_TR31_INFO attribute.

Example:

--tr31-header-file=./tr31.txt

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-g, --gen-comp

Generate key components.

-h, -?, --help

Display usage information.

-i<hexstring>, --id=<hexstring>

Specifies the CKA_ID value.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-j, --pkcs12

Export to PKCS#12 format.

-pkLabel

Private Key to be exported to PKCS#12 file.

-keyCertLabel

Certificate Label to be exported to PKCS#12 file.

-pkalgo

Private Key Encryption Algorithms. This parameter is optional. The default setting is DES3. Possible settings are: RC4_128, RC4_40, DES3, DES2, RC2_128, RC2_40.

Note

If FIPS Mode is ON, then none of the algorithms in the RC family are allowed.

-certalgo

Certificate Encryption Algorithm. This parameter is optional. In FIPS Mode the default setting is DES3. If FIPS Mode is OFF, the default setting is RC2_40. Possible settings are: RC4_128, RC4_40, DES3, DES2, RC2_128, RC2_40.

-k<numb>, --num-comp =<numb>

Number of key components required to be entered or number to be generated (when -g parameter is specified).

-l<label>, --label =<label>

Specify label.

-m, --multi-part

Do a multi-part key entry for console import/export.

--mech-list=<mechanism-list>

This specifies the contents of a CKA_MECHANISM_LIST attribute to add to the new key.

The <mechanism-list> is a comma-separated list of mechanism names. For example:

--mech-list=WRAP_TR31_DERIVE,WRAP_TR31_VARIANT

The CKA_MECHANISM_LIST attribute further restricts the possible mechanisms that can be used with the key.

Note

• This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

The presence of a mechanism in the list does not enable a mechanism that would not normally be allowed with that key.

-M, --NofM

Causes the N of M scheme to be used for a multiple-custodians backup. This means that the key is split in such a way that the original key can be recovered with the cooperation of any of the custodians with a user specified, minimum number of custodians being required.

-n<name>, --name =<name>

Name of the object to operate on.

-O, --SO-PIN

Change the Security Officer PIN. Used with the change PIN command.

-o <userpin>

Specifies the Security Officer PIN in the command line along with the command, instead of prompting for it afterwards. Useful for automation, but not recommended for use in production environments since the password is exposed in plaintext. Can be specified with all commands that require SO login.

-p, --pinpad

Use a supported PIN pad device for entering key components. See PIN pad key entry for complete PIN pad instructions.

--rsaPubLen<bits>

This option specifies the length (in bits) of a random RSA public exponent.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

--rsaPubVal<hex-string>

This option specifies the value of the RSA public exponent as a HEX string.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-s<slot>, --slot-num =<slot>

Specifies the slot to operate on. Default is 0 (zero), however must be specified when using the l command and -v option for Slot 0.

--subPrimeSize=<size>

This option specifies the size of the sub prime during X9_42 generation. Default is 224.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-t<type>, --type=<type>

The type of key to create. Valid values:

• aes

• aria

• des

• des2

• des3

• rc2

• rc4

• cast

• idea

• seed

• gs

• rsa

  Note

  If -t is set to this value and values are not specified for --rsaPubLen and --rsaPubVal, then the default is to use a random exponent of length 16 (17 if the FIPS Algorithms Only security flag is enabled).

• dsa

• dsa_params

• dh

• x942dh

  Note

  -t can only be set to this value if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

• x942dh_params

  Note

  -t can only be set to this value if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

• dh_params

• ec

  Note

  If -t is set to this value, the -C parameter must be included in the command otherwise ctkmu will exit with an error message. Valid values for -C are described in -C.

• ec_edwards

  Note

  If -t is set to this value, the -C parameter must be included in the command otherwise ctkmu will exit with an error message. Valid values for -C are described in -C.

• ec_mont

  Note

  -t can only be set to this value if you are using ProtectToolkit 7.2.0 or newer with ProtectServer 3 HSM Firmware 7.02.00 or newer.

  If -t is set to this value, the -C parameter must be included in the command otherwise ctkmu will exit with an error message. Valid values for -C are described in -C.

--tr31method= <method>

This option specifies the key binding method used with the TR31 export method. Valid options:

• derive-cbc – type ‘B’ if KBPK is DES2/DES3 or type ‘D’ if KBPK is an AES. (Default).

• derive-ctr – type ‘E’, KBPK must be AES (currently not supported).

• variant-cbc – type ‘C’, KBPK must be DES2/DES3.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

--tr31-pubkey

Import public key from TR31 key block. Default: private.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-u <userpin>

Specifies the slot user PIN in the command line along with the command, instead of prompting for it afterwards. Useful for automation, but not recommended for use in production environments since the password is exposed in plaintext. Can be specified with all commands that require token login.

-v, --verbose

Displays the attributes that ctkmu can change.

-w<name>, --wrap-key =<name>

Name of the key used to wrap or unwrap.

Note

If you are specifying a DES3 key as the wrapping key for an export key operation (with the x command), you must also include the -3 option. If -3 is not included, the operation fails and an Export operation failed 0x63 - key type inconsistent error is returned.

-y, --console

Import or export using the console.

Note

You cannot use this option to import the public key of an asymmetric key pair by using the console.

-z<size>, --size=<size>

Size of the key to create/import (for AES, RC2, RC4, CAST, RSA, DSA and generic secret).

Note

If the FIPS Mode security policy is enabled, the cryptographic operations of RSA, DSA, DH, and EC algorithms are restricted to key sizes within a specified range. For more information about the size limitations of keys that are created or imported in FIPS Mode, see FIPS Mode operational restrictions.

-3, --PTKC3

Generate export to smart card and file using the ProtectToolkit-C version 3 format (CKM_WRAPKEY_DES3_CBC), instead of the default wrapping mechanism (CKM_WRAPKEY_AES_KWP). Used when exporting keys to be sent to older style HSMs.

Note

Wrapping and unwrapping operations using this option will fail in FIPS Mode.

-4, --PTKC4

Generate export to smart card and file using the ProtectToolkit-C version 4 format (CKM_WRAPKEY_AES_CBC), instead of the default wrapping mechanism (CKM_WRAPKEY_AES_KWP). Used when exporting keys to be sent to older style HSMs.

Note

Wrapping operations using this option will fail in FIPS Mode.

Exit status

The ctkmu utility will return a zero(0) exit status when successful. A non-zero exit status is returned on an error. Warnings are not treated as errors.